Repository navigation
Add an optional local MCP server - #10472
Open
filipecavalc wants to merge 7 commits into
Open
filipecavalc wants to merge 7 commits into
filipecavalc wants to merge 7 commits into
Conversation
Path of Building can now serve the Model Context Protocol over Streamable HTTP on 127.0.0.1, so MCP clients can read and drive the open build. It is off by default and enabled from Options, Local MCP server. - McpHttp and McpProtocol handle HTTP and JSON-RPC without sockets, serving protocol version 2026-07-28 and the initialize-based 2025 versions on the same endpoint, with Host, Origin and bearer token checks. - McpServer polls non-blocking sockets from main:OnFrame and keeps frames running while the window is in the background, throttled when idle. - McpTools holds the tools; this adds status, the builds list, opening, saving and exporting builds, side bar stats, level and notes, and simulate. - Small refactors so the server reuses existing logic: main:ProcessModeChange, build:ProcessBuildFlag, build:HasUnsavedChanges, ItemsTab:GetSlotReplacementOverride and PassiveTreeView:ParseSearchString.
- Send HTTP/1.1 responses chunked. Security software that inspects MCP traffic was seen rewriting Content-Length responses on /mcp to chunked framing without re-encoding the body, which corrupted every reply; responses that are already chunked pass through intact. - Only count cursor movement as use of the window shortly after a key or click in it, and wait longer between idle frames the longer the window stays idle (up to 1 s; a request still wakes it at once). - Report a tool file that fails to load instead of failing startup.
Adds the remaining tools, grouped by the part of the window they use: - Tree: tree_get, tree_search, tree_edit, tree_specs, tree_node_power, tree_timeless_jewel, tree_tattoos - Items: items_get, items_equip, items_sets, items_db_search, items_craft, trade_query - Skills and Config: skills_get, skills_edit, skills_rank_supports, config_get, config_set - Calcs: calcs_breakdown - Compare, Party and import: compare_builds, compare_copy, party, import_character Each drives the same functions the tab's controls use and restores any dialog or selection it borrows. PoB changes: - SkillsTab:PasteSocketGroup(text) now uses its argument before the clipboard (Ctrl+V passes none, so it is unchanged). - CompareTab and CompareBuySimilar export the helpers the comparison report shares with the tab. - build_open defers link downloads through T.Settle so failures reach the client instead of the download callback. Adds docs/mcp.md and specs for every tool.
- Replacing the open build only sets abortSave right before the switch, so a failed build_open or import no longer closes the build on the next frame outside Dev Mode; build XML is validated before anything is replaced, and a new build's class and ascendancy before it opens. - Deferred calls answer exactly once, never apply a result that arrives after their timeout, refuse to change the build while the user has a dialog open, and close only the dialogs they opened themselves. A tool that fails after changing something still marks the build unsaved and says so. - Malformed chunked bodies are answered with 400 instead of raising, the bytes buffered per connection are capped, and unexpected errors while handling a request are answered with 500. - Poll runs at the start of main:OnFrame, before input is handled, so typing or using a dialog counts as using the window. - build_save refuses while a dialog is open, never runs a pending save action, and restores the build's name and file when writing fails. - config_set checks the custom modifier group before changing options. - Host and Origin must carry this server's port. - Comparison and import callbacks detect another build opening by its tabs. - Editing tools that remove or overwrite are marked destructive.
… build Also offer the trader's Megalomaniac, Watcher's Eye and Pearl of Tsoatha rows and its enchant/anoint behaviour, and split the trader's evaluation, sorting, result preparation and listing link out of its row code so they can be reused.
filipecavalc
marked this pull request as ready for review
November 16, 2026 23:42
…ild, a code or a link Guides keep their stages and advice in the Notes tab; the compare_with_guide prompt now reads them first.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of the problem being solved:
Path of Building knows everything about a build, but no other program can ask it anything. Tools that want its numbers re-implement the calculations, or run it headless with their own glue code (a headless JSON-RPC proposal, #9505, went stale).
This PR adds an optional, off-by-default server inside Path of Building that speaks the Model Context Protocol (MCP), the open standard that many desktop and command-line clients use to call local tools. Once it is enabled in Options, an MCP client on the same computer can read the open build, measure changes with PoB's own calculator, make changes the way the UI does (they show live in the window and stay unsaved until the user decides), and use PoB's features: the trader, the timeless jewel finder, crafting, the Compare tab and more. Every number comes from PoB's calculations; nothing is re-implemented.
Video walkthrough (4:31)
Watch on YouTube (unlisted, 4:31)
The video shows a real session: an MCP client analysing a build, finding a helmet on the trade site, equipping it, allocating the best passive, and a tour of the other tools, then how the code fits into PoB. Every Path of Building shot was recorded by PoB itself while the client was driving it.
Turning it on
The dialog shows the status, the port (default 49290), the token (copy / new), a Copy client configuration button (a ready
mcpServersJSON for clients) and the last requests, so the user can see what a client did.Changes happen live in the window
An item equipped by a client (
items_equip, here the best helmettrade_searchfound):A passive allocated by a client (
tree_edit, the nodetree_node_powerranked first):A configuration option changed by a client (
config_set), with the side bar following:Excerpts of the real session shown in the video (prompts and the client's answers, built from the tools' results)
What a client can do: 33 tools, grouped by tab
app_statusbuilds_listbuild_openbuild_savebuild_exportbuild_notesbuild_statsbuild_editsimulatecalcs_breakdowntree_gettree_searchtree_edittree_specstree_node_powertree_timeless_jeweltree_tattoositems_getitems_equipitems_setsitems_db_searchitems_crafttrade_querytrade_searchskills_getskills_editskills_rank_supportsconfig_getconfig_setcompare_buildscompare_copypartyimport_characterPlus four prompts (
analyze_build,compare_with_guide,best_upgrade,timeless_jewel) and the open build's XML as the resourcepob://build/current.xml. Read-only tools are annotated as such for clients, and tools that change or replace the build are marked destructive.How it fits
flowchart LR C["MCP client"] -->|"POST /mcp<br/>Bearer token"| S subgraph PoB["Path of Building, main thread"] M["main:OnFrame"] --> S["McpServer:Poll<br/>LuaSocket, 127.0.0.1"] S --> H["McpHttp<br/>HTTP/1.1, pure Lua"] H --> P["McpProtocol<br/>JSON-RPC, MCP versions,<br/>Host / Origin / token"] P --> T["McpTools<br/>dialog guard, unsaved state,<br/>stat changes, deferred calls"] T --> F["McpTools/*.lua<br/>Build, Tree, Items, Trade,<br/>Skills, Config, Calcs, Compare"] F --> X["PoB's own code<br/>calcsTab, spec, itemsTab, skillsTab,<br/>TradeQuery, CompareTab, ..."] endsequenceDiagram participant C as MCP client participant S as McpServer (in main:OnFrame) participant T as McpTools participant B as Build / tabs C->>S: tools/call items_equip S->>T: parsed request T->>T: refuse if a dialog is open, check the build T->>B: the same functions the Items tab calls T->>B: modFlag + ProcessBuildFlag (recalculate) T-->>C: result + side bar changes (as PoB's tooltips word them) Note over B: drawn in the same frame, marked unsavedModules/McpHttp.luaandModules/McpProtocol.lua: HTTP/1.1 and MCP over Streamable HTTP, pure Lua without sockets, so they are unit tested. They serve protocol version 2026-07-28 and theinitialize-based 2025 versions on the same endpoint ("dual-era" server); JSON responses only, no SSE, no sessions.Modules/McpServer.lua: LuaSocket (already shipped and used byLaunchServer.lua), non-blocking, polled once per frame frommain:OnFrame; everything runs on the main thread between frames. SimpleGraphic skipsOnFramefor an unfocused window unless a coroutine is suspended, so the server keeps one suspended while it is enabled, and waits insocket.selectwhile nobody uses the window (a request wakes it at once).Modules/McpTools.luaandModules/McpTools/*.lua: the tool framework and the tools, one file per tab. Tools call the same functions the UI's controls call wherever possible.main:ProcessModeChange,build:ProcessBuildFlag,build:HasUnsavedChanges,ItemsTab:GetSlotReplacementOverride,PassiveTreeView:ParseSearchString, exported helpers inCompareTab/CompareBuySimilar, and inTradeQuery:EvaluateItem,GetEvaluationSlotName,SortResults,PrepareGeneratedResultsandBuildListingSearchUrlsplit out of the row code, optional realm/league/weights parameters,sortModesset in the constructor, andSetNoticetolerating a trader that was never opened.SkillsTab:PasteSocketGroup(text)read the clipboard before its argument; the argument now wins (Ctrl+V passes none, so it is unchanged).docs/mcp.md(users and developers).Safety
127.0.0.1only. Every request needs a bearer token (stored inSettings.xmllike the Path of Exile login tokens).HostandOriginare checked, so web pages cannot reach it (DNS rebinding).abortSave).build_savewrites build files, and it never replaces another existing file without an explicit flag.build.timelessData, remembered selections, display item).Trying it
{ "mcpServers": { "path-of-building": { "type": "http", "url": "http://127.0.0.1:49290/mcp", "headers": { "Authorization": "Bearer <token from the dialog>" } } } }Without a client: one request with curl
Footprint on existing code
Almost all of the diff is new files. Changes to code that already existed are small and behaviour-neutral:
Modules/Mcp*.lua,Modules/McpTools/*.luaspec/System/TestMcp*_spec.luadocs/mcp.mdMain.lua,Build.lua,ItemsTab.lua,PassiveTreeView.lua,SkillsTab.lua,CompareTab.lua,CompareBuySimilar.lua,TradeQuery.luaruntime/socket.dll, already used byLaunchServer.lua),dkjsonandbase64, all already inruntime/lua.LaunchServer.luaalready relies on there.Cost and robustness
simulateof an item: ~45 ms. A trade search of 20 listings: ~2 s.Content-Lengthresponses on/mcpinto chunked framing without re-encoding the body, corrupting every reply; already-chunked responses pass intact.Steps taken to verify a working solution:
spec/System/TestMcp*_spec.lua(75 tests): HTTP parsing and framing (including malformed input); Host/Origin/token checks; both protocol eras, header validation, version errors; every tool against headless builds, checking results equal what PoB computes (e.g.simulateof an item equals equipping it), edits are visible in PoB's objects, read-only tools change nothing, failed build replacements leave the open build untouched, trade searches against recorded trade site responses, and no dialog is left open. The full suite passes (786 tests) on top of the currentdev.Link to a build that showcases this PR:
Any build; the feature is independent of build content.
Before screenshot:
N/A: before this PR there is no server and no Local MCP server row in Options.
After screenshot:
A client's change shown live in the window:
Notes for reviewers. The diff is large, most of it the tool files and their specs. If you prefer, it splits cleanly into separate PRs: (1) server, protocol and read-only tools; (2) editing tools; (3) the advanced Tree tab tools; (4) Items/Trade/Compare/Party/Import. I am happy to adjust names, defaults, the Options UI or anything else to fit the project.